home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_exim.idb / usr / freeware / catman / p_man / cat3 / ident.Z / ident
Encoding:
Text File  |  1999-01-26  |  12.9 KB  |  265 lines
  1.  
  2.  
  3.  
  4.      IIIIDDDDEEEENNNNTTTT((((3333NNNN))))        LLLLyyyyssssaaaattttoooorrrr    AAAACCCCSSSS ((((4444 AAAApppprrrriiiillll 1111999999993333))))         IIIIDDDDEEEENNNNTTTT((((3333NNNN))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.       ident_lookup,    ident_id, ident_free, id_open, id_close,
  10.       id_query, id_parse, id_fileno    - query    remote IDENT server
  11.  
  12.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.       ####iiiinnnncccclllluuuuddddeeee <<<<iiiiddddeeeennnntttt....hhhh>>>>
  14.  
  15.       _H_i_g_h-_l_e_v_e_l _c_a_l_l_s
  16.  
  17.       IIIIDDDDEEEENNNNTTTT    ****iiiiddddeeeennnntttt____llllooooooookkkkuuuupppp((((iiiinnnntttt ffffdddd,,,, iiiinnnntttt ttttiiiimmmmeeeeoooouuuutttt))))
  18.  
  19.       cccchhhhaaaarrrr ****iiiiddddeeeennnntttt____iiiidddd((((iiiinnnntttt ffffdddd,,,, iiiinnnntttt ttttiiiimmmmeeeeoooouuuutttt))))
  20.  
  21.       vvvvooooiiiidddd iiiiddddeeeennnntttt____ffffrrrreeeeeeee((((IIIIDDDDEEEENNNNTTTT    ****iiiidddd))))
  22.  
  23.       _L_o_w-_l_e_v_e_l _c_a_l_l_s
  24.  
  25.       iiiidddd____tttt ****iiiidddd____ooooppppeeeennnn((((llllaaaaddddddddrrrr,,,, ffffaaaaddddddddrrrr,,,, ttttiiiimmmmeeeeoooouuuutttt))))
  26.       ssssttttrrrruuuucccctttt iiiinnnn____aaaaddddddddrrrr ****llllaaaaddddddddrrrr,,,, ****ffffaaaaddddddddrrrr;;;;
  27.       ssssttttrrrruuuucccctttt ttttiiiimmmmeeeevvvvaaaallll ****ttttiiiimmmmeeeeoooouuuutttt;;;;
  28.  
  29.       iiiinnnntttt iiiidddd____cccclllloooosssseeee((((iiiidddd))))
  30.       iiiidddd____tttt ****iiiidddd;;;;
  31.  
  32.       iiiidddd____qqqquuuueeeerrrryyyy((((iiiidddd,,,, llllppppoooorrrrtttt,,,, ffffppppoooorrrrtttt,,,, ttttiiiimmmmeeeeoooouuuutttt))))
  33.       iiiidddd____tttt ****iiiidddd;;;;
  34.       iiiinnnntttt llllppppoooorrrrtttt,,,, ffffppppoooorrrrtttt;;;;
  35.       ssssttttrrrruuuucccctttt ttttiiiimmmmeeeevvvvaaaallll ****ttttiiiimmmmeeeeoooouuuutttt;;;;
  36.  
  37.       iiiinnnntttt iiiidddd____ppppaaaarrrrsssseeee((((iiiidddd,,,, ttttiiiimmmmeeeeoooouuuutttt,,,, llllppppoooorrrrtttt,,,, ffffppppoooorrrrtttt,,,, iiiiddddeeeennnnttttiiiiffffiiiieeeerrrr,,,,
  38.             ooooppppssssyyyyssss,,,, cccchhhhaaaarrrrsssseeeetttt))))
  39.       iiiidddd____tttt ****iiiidddd;;;;
  40.       ssssttttrrrruuuucccctttt ttttiiiimmmmeeeevvvvaaaallll ****ttttiiiimmmmeeeeoooouuuutttt;;;;
  41.       iiiinnnntttt ****llllppppoooorrrrtttt,,,, ****ffffppppoooorrrrtttt;;;;
  42.       cccchhhhaaaarrrr ********iiiiddddeeeennnnttttiiiiffffiiiieeeerrrr,,,, ********ooooppppssssyyyyssss,,,, ********cccchhhhaaaarrrrsssseeeetttt;;;;
  43.  
  44.       iiiinnnntttt iiiidddd____ffffiiiilllleeeennnnoooo((((iiiidddd))))
  45.       iiiidddd____tttt ****iiiidddd;;;;
  46.  
  47.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  48.       iiiiddddeeeennnntttt____llllooooooookkkkuuuupppp tries to    connect    to a remote IIIIDDDDEEEENNNNTTTT server to
  49.       establish the    identity of the    peer connected on _f_d, which
  50.       should be a socket file descriptor.  _t_i_m_e_o_u_t is the longest
  51.       permissible time to block waiting for    an answer, and is
  52.       given    in seconds. A value of 0 (zero)    means wait
  53.       indefinitely (which in the most extreme case will normally
  54.       be until the underlying network times    out).  iiiiddddeeeennnntttt____llllooooooookkkkuuuupppp
  55.       returns a pointer to an _I_D_E_N_T    struct,    which has the
  56.       following contents:
  57.  
  58.            ttttyyyyppppeeeeddddeeeeffff ssssttttrrrruuuucccctttt {{{{
  59.             iiiinnnntttt    llllppppoooorrrrtttt;;;;        ////**** LLLLooooccccaaaallll ppppoooorrrrtttt ****////
  60.  
  61.  
  62.  
  63.      Page 1                        (printed 12/10/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      IIIIDDDDEEEENNNNTTTT((((3333NNNN))))        LLLLyyyyssssaaaattttoooorrrr    AAAACCCCSSSS ((((4444 AAAApppprrrriiiillll 1111999999993333))))         IIIIDDDDEEEENNNNTTTT((((3333NNNN))))
  71.  
  72.  
  73.  
  74.             iiiinnnntttt    ffffppppoooorrrrtttt;;;;        ////**** FFFFaaaarrrr ((((rrrreeeemmmmooootttteeee))))    ppppoooorrrrtttt ****////
  75.             cccchhhhaaaarrrr ****iiiiddddeeeennnnttttiiiiffffiiiieeeerrrr;;;;    ////**** NNNNoooorrrrmmmmaaaallllllllyyyy uuuusssseeeerrrr nnnnaaaammmmeeee ****////
  76.             cccchhhhaaaarrrr ****ooooppppssssyyyyssss;;;;    ////**** OOOOSSSS ****////
  77.             cccchhhhaaaarrrr ****cccchhhhaaaarrrrsssseeeetttt;;;;    ////**** CCCChhhhaaaarrrrsssseeeetttt ((((wwwwhhhhaaaatttt ddddiiiidddd yyyyoooouuuu eeeexxxxppppeeeecccctttt????)))) ****////
  78.            }}}} IIIIDDDDEEEENNNNTTTT;;;;
  79.  
  80.       For a    full description of the    different fields, refer    to
  81.       _R_F_C-_1_4_1_3.
  82.  
  83.       All data returned by iiiiddddeeeennnntttt____llllooooooookkkkuuuupppp (including the IDENT
  84.       struct) points to malloc'd data, which can be    freed with a
  85.       call to iiiiddddeeeennnntttt____ffffrrrreeeeeeee.... iiiiddddeeeennnntttt____llllooooooookkkkuuuupppp returns 0 on    error or
  86.       timeout. Presently, this should normally be taken to mean
  87.       that the remote site is not running an IDENT server, but it
  88.       might    naturally be caused by other network related problems
  89.       as well.  NNNNooootttteeee tttthhhhaaaatttt all fields of the    IDENT struct need not
  90.       necessarily be set.
  91.  
  92.       iiiiddddeeeennnntttt____iiiidddd takes the same parameters as    iiiiddddeeeennnntttt____llllooooooookkkkuuuupppp but only
  93.       returns a pointer to a malloc'd area containing the
  94.       _i_d_e_n_t_i_f_i_e_r string, which is probably the most    wanted data
  95.       from the IDENT query.
  96.  
  97.       iiiiddddeeeennnntttt____ffffrrrreeeeeeee frees all data areas associated with the IDENT
  98.       struct pointed to by _i_d, including the struct    itself.
  99.  
  100.                   _L_o_w-_l_e_v_e_l    _c_a_l_l_s
  101.  
  102.       The low-level    calls can be used when greater flexibility is
  103.       needed. For example, if non-blocking I/O is needed, or
  104.       multiple queries to the same host are    to be made.
  105.  
  106.       iiiidddd____ooooppppeeeennnn opens    a connection to    the remote IDENT server
  107.       referred to by _f_a_d_d_r.    The timeout is specified by _t_i_m_e_o_u_t. A
  108.       null-pointer means wait indefinitely,    while a    pointer    to a
  109.       zero-valued _t_i_m_e_v_a_l struct sets non-blocking I/O, in the
  110.       same way as for sssseeeelllleeeecccctttt((((2222)))).... iiiidddd____ooooppppeeeennnn returns a pointer to an
  111.       iiiidddd____tttt datum, which is an opaque structure to be used as
  112.       future reference to the opened connection. When using    non-
  113.       blocking I/O it might    however    be useful to access the
  114.       underlying socket file descriptior, which can    be gotten at
  115.       through the iiiidddd____ffffiiiilllleeeennnnoooo    macro described    below.
  116.  
  117.       iiiidddd____cccclllloooosssseeee closes the connection opened    with iiiidddd____ooooppppeeeennnn and frees
  118.       all data associated with _i_d.
  119.  
  120.       iiiidddd____qqqquuuueeeerrrryyyy sends off a query to    a remote IDENT server.    _l_p_o_r_t
  121.       and _f_p_o_r_t are    sent to    the server to identify the connection
  122.       for which identification is needed.  _t_i_m_e_o_u_t is given    as for
  123.       iiiidddd____ooooppppeeeennnn.... If successful, iiiidddd____qqqquuuueeeerrrryyyy returns the number of bytes
  124.       sent to the remote server. If    not, -1    is returned and    eeeerrrrrrrrnnnnoooo
  125.       is set.
  126.  
  127.  
  128.  
  129.      Page 2                        (printed 12/10/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      IIIIDDDDEEEENNNNTTTT((((3333NNNN))))        LLLLyyyyssssaaaattttoooorrrr    AAAACCCCSSSS ((((4444 AAAApppprrrriiiillll 1111999999993333))))         IIIIDDDDEEEENNNNTTTT((((3333NNNN))))
  137.  
  138.  
  139.  
  140.       iiiidddd____ppppaaaarrrrsssseeee parses the reply to a query sent off    by iiiidddd____qqqquuuueeeerrrryyyy
  141.       and returns information to the locations pointed to by
  142.       _l_p_o_r_t, _f_p_o_r_t,    _i_d_e_n_t_i_f_i_e_r, _o_p_s_y_s and _c_h_a_r_s_e_t. For string data
  143.       (_i_d_e_n_t_i_f_i_e_r, _o_p_s_y_s and _c_h_a_r_s_e_t) pointers to malloc'd space
  144.       are returned.
  145.  
  146.       iiiidddd____ppppaaaarrrrsssseeee returns:
  147.  
  148.         1   If completely successful.
  149.  
  150.            -3   Illegal reply type from remote server.  _i_d_e_n_t_i_f_i_e_r
  151.             is set to the illegal reply.
  152.  
  153.            -2   Cannot parse the reply from    the server.
  154.             _i_d_e_n_t_i_f_i_e_r is normally set to the illegal reply.
  155.  
  156.            -1   On general errors or timeout.
  157.  
  158.         0   When non-blocking mode is set and iiiidddd____ppppaaaarrrrsssseeee has not
  159.             finished parsing the reply from the    remote server.
  160.  
  161.         2   Indicates the query/reply were successful, but the
  162.             remote server experienced some error.  _i_d_e_n_t_i_f_i_e_r
  163.             is set to the error    message    from the remote
  164.             server.
  165.  
  166.       For all errors, _e_r_r_n_o    is set as appropriate.
  167.  
  168.       iiiidddd____ffffiiiilllleeeennnnoooo is a macro that takes an iiiidddd____tttt handle and returns
  169.       the actual socket file descriptor used for the connection to
  170.       the remote server.
  171.  
  172.      EEEERRRRRRRROOOORRRRSSSS
  173.       ETIMEDOUT     The call timed    out and    non-blocking I/O was
  174.              not set.
  175.  
  176.      EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  177.       Here's an example how    to handle the reply from id_reply() in
  178.       the case that    non-blocking I/O is set. Note that id_reply()
  179.       will return 0    as long    as it's    not finished parsing a reply.
  180.  
  181.            int rcode;
  182.  
  183.         ...
  184.  
  185.            idp = id_open(...)
  186.  
  187.         ...
  188.  
  189.            while ((rcode = id_parse(idp, timeout,
  190.                    &lport, &fport, &id, &op, &cs)) == 0)
  191.             ;
  192.  
  193.  
  194.  
  195.      Page 3                        (printed 12/10/98)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      IIIIDDDDEEEENNNNTTTT((((3333NNNN))))        LLLLyyyyssssaaaattttoooorrrr    AAAACCCCSSSS ((((4444 AAAApppprrrriiiillll 1111999999993333))))         IIIIDDDDEEEENNNNTTTT((((3333NNNN))))
  203.  
  204.  
  205.  
  206.            if (rcode < 0)
  207.            {
  208.          if (errno == ETIMEDOUT)
  209.            foo();     /* Lookup    timed out */
  210.          else
  211.            bar();      /* Fatal    error */
  212.            }
  213.            else if (rcode == 1)
  214.            {
  215.          /* Valid USERID protocol reply    */
  216.            }
  217.            else if (rcode == 2)
  218.            {
  219.          /* Protocol ERROR reply */
  220.            }
  221.  
  222.      SSSSEEEEEEEE AAAALLLLSSSSOOOO
  223.       RFC-1413, socket(2), select(2)
  224.  
  225.      AAAAUUUUTTTTHHHHOOOORRRRSSSS
  226.       Peter    Eriksson <_p_e_n@_l_y_s_a_t_o_r._l_i_u._s_e>
  227.       P"ar Emanuelsson <_p_e_l_l@_l_y_s_a_t_o_r._l_i_u._s_e>
  228.  
  229.      BBBBUUUUGGGGSSSS
  230.       For iiiiddddeeeennnntttt____llllooooooookkkkuuuupppp and iiiiddddeeeennnntttt____iiiidddd    the blocking time in extreme
  231.       cases    might be as much as three times    the value given    in the
  232.       _t_i_m_e_o_u_t parameter.
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                        (printed 12/10/98)
  262.  
  263.  
  264.  
  265.